package com.core.gwt.place.client;

import com.google.gwt.place.shared.Place;
import com.google.gwt.place.shared.PlaceHistoryMapper;
import com.google.gwt.place.shared.PlaceTokenizer;
import com.google.gwt.place.shared.Prefix;
import com.google.gwt.place.shared.WithTokenizers;

/**
 * An abstract base class for {@link Place} implementations, a
 * {@link TokenizablePlace} which offers an alternative mechanism for mapping
 * URL tokens to/from {@link Place} objects, replacing the built-in GWT features
 * ({@link PlaceTokenizer} implementations annotated with {@link Prefix} and a
 * generated {@link PlaceHistoryMapper} implementation based on the
 * {@link WithTokenizers} annotation).<br>
 * <br>
 * The {@link PlaceTokenizer} interface and the {@link Prefix} annotation are
 * replaced by the {@link PlaceType} interface, which exposes a method to
 * retrieve the unique prefix for the place and a method to get a place instance
 * initialized from a token.<br>
 * <br>
 * Your {@link Place} implementations extending this class must declare a public
 * static {@link PlaceType} field and implement the {@link #getType} abstract
 * method.<br>
 * 
 * <pre>
 * public class SomePlace extends PlaceWithType {
 *     ...
 *     private static String PREFIX = "some";
 *     
 *     public static PlaceType TYPE = new PlaceType() {
 *        {@literal @Override}
 *         public PlaceWithType getPlace(final String token) {
 *             return new SomePlace(token);
 *         }
 *         
 *        {@literal @Override}
 *         public String getPrefix() {
 *             return PREFIX;
 *         }
 *     }
 *     ...
 *    {@literal @Override}
 *     public PlaceType getType() {
 *         return TYPE;
 *     }
 *     ...
 * }
 * </pre>
 * 
 * Your application's place types can then be added to the
 * {@link PlaceHistoryMapperUsingPlaceType} instance used as the application's
 * {@link PlaceHistoryMapper}.
 * 

 */
public abstract class PlaceWithType extends TokenizablePlace {
	public PlaceWithType() {
		super();
	}

	/**
	 * Initializes a {@link PlaceWithType} from a URL token.
	 */
	public PlaceWithType(final String token) {
		super(token);
	}

	/**
	 * Returns the the {@link PlaceType} object for this place.
	 */
	public abstract PlaceType getType();
}
